Documentation

# Global Settings Configuration

Configures global service settings including provisioning behavior, migration options, email, archiving, and Yammer authentication.

Referenced by: Root SharepointCfg.SettingsCfg (singular).

# Overview

SettingsCfg is a container for all global service settings that affect how the provisioning service operates, including provisioning preferences, migration settings, email configuration, and archiving rules.

Nested configurations:

  • SettingsProvisioningCfg — provisioning-specific settings
  • SettingsMigrateCfg — migration settings
  • EmailCfg — email/SMTP configuration
  • YammerAuthenticationCfg — Yammer authentication
  • ArchivingCfg — archiving rules

# Applied when

Global settings are applied when:

  • The provisioning service starts; these are root-level configuration settings that affect all provisioning operations
  • SettingsCfg is always loaded from the root SharepointCfg object and applied during service initialization
  • Settings in this configuration control:
    • Provisioning behavior (SettingsProvisioningCfg) — how sites, libraries, and other objects are created
    • Migration behavior (SettingsMigrateCfg) — how data migrations are processed
    • Email (EmailCfg) — SMTP server and email notifications
    • Authentication (YammerAuthenticationCfg) — Yammer OAuth configuration
    • Archiving (ArchivingCfg) — site archiving policies and retention rules
  • Changes to global settings take effect on the next service restart; already-running provisioning jobs are not affected

# Core settings

# Debug

Type: bool | Default: false | Required: No

Enable debug mode (verbose logging).

# RequestTimeout

Type: int | Default: 900 | Required: No

Request timeout in seconds for operations.

# Provisioning settings

# Provisioning

Type: SettingsProvisioningCfg | Default: — | Required: No

Provisioning-specific settings (see below).

# SettingsProvisioningCfg

# CreateTermIfNotFound

Type: bool | Default: true | Required: No

When enabled, taxonomy (managed metadata) terms referenced by a column value that do not yet exist in the term store are created automatically. When disabled, a value with no matching term is left unset.

# CleanupCompletedMonitorDirectory

Type: int (Configurator: "Cleanup Monitor and log Directory after X days") | Default: 14 | Required: No

Files in the monitor and log directories older than this many days are removed automatically by the Cleanup Completed Monitor Directory job. Specify 0 to disable cleanup entirely.

# CleanupCompletedMonitorDirectoryFilters

Type: string (list) | Default: ["json"] | Required: No

Restricts the cleanup above to files with these extensions. Leave empty to remove files of any extension (the age threshold above still applies).

# LockConcurrentEqualClientMattersMaxPeriod

Type: int | Default: 30 | Required: No

Maximum time, in minutes, that a request for a client/matter code will wait for another in-progress request for the same client/matter code to finish before proceeding. Prevents two concurrent requests for the same matter from racing each other during provisioning.

# CountDoclibSitesTimeoutInSeconds

Type: int (Configurator: "Timeout (in seconds) to count doclibs/sites") | Default: 360 | Required: No

Maximum time, per site, to wait when counting the number of document libraries or sub-sites already provisioned under it. Only applies when ClientMatterDesign is MatterSite, ClientSite_MatterSite, ClientSite_MatterDocLib, or MatterDocLib — designs where the matter is added to an existing site rather than a dedicated site collection.

# ReadOnlyContentTypeGroups

Type: string (list) | Default: ["DMS"] | Required: No

Content type groups that are made read-only (true) immediately after a site collection is created, before the Document ID provider is activated on it.

# MatterListTitleFormat / MatterListTitleFormatCustom

Type: enum (Name, Name_Code, Code_Name, Code, Custom) | Default: Name_Code | Required: No

Controls how the matter list item title is generated from the matter's code and name when no explicit Title is supplied. Setting MatterListTitleFormatCustom to a non-empty value (e.g. {MatterName} ({MatterCode}) – {Responsible}, resolved via dynamic name values) automatically switches MatterListTitleFormat to Custom; clearing it switches back to Name_Code.

# ClientListTitleFormat / ClientListTitleFormatCustom

Type: enum (Name, Name_Code, Code_Name, Code, Custom) | Default: Name | Required: No

Same as MatterListTitleFormat/MatterListTitleFormatCustom above, but for the client list item title. Setting ClientListTitleFormatCustom to a non-empty value switches ClientListTitleFormat to Custom; clearing it switches back to Name.

# MyMattersListColumnName

Type: string | Default: — | Required: No

Semicolon-separated list of dynamic name templates (e.g. {Responsible};{Secretary}) resolved against the matter's properties to determine which users are automatically added to the My Matters list when a matter is created or updated. Each template can resolve to one user or a semicolon-separated list of users. Only used as a fallback when the request does not already specify users explicitly (e.g. via the MyMattersList column/field on the Client Matter handler).

# MatterListForceSiteUrl

Type: bool | Default: false | Required: No

By default, the matter list's Url column is set to the site's URL when the matter has more than one document library (there is no single library to link to), or to that one document library's URL when there is exactly one. Enabling this setting always uses the site's URL, even when the matter has exactly one document library.

# MatterListMonitorDirectory

Type: string | Default: — | Required: No

When set, enables the "master monitor directory" mechanism: after a matter is successfully provisioned, ClientList_<ClientCode>.json and MatterList_<ClientCode>_<MatterCode>.json files are written to this directory so a secondary service instance watching it can keep its own client/matter lists synchronized. See Client Matter execution flow → Master monitor directory.

# UpdateDefaultValuesOnDocumentsMonitorDirectory

Type: string | Default: — | Required: No

When set, an AssignDefaultValuesInDocLib_<ClientCode>_<MatterCode>.json file is written to this directory after a matter is provisioned, triggering the Update Default Values handler to apply the matter's metadata as default column values on existing documents. See Client Matter execution flow → Update default values.

# Matter status, extranet, and CSV settings

MatterStatusColumnName, MatterStatusOpenedValues, and MatterStatusClosedValues control matter open/closed status parsing — see Client Matter execution flow → Matter status parsing. Extranet configures the extranet integration — see Extranet integration. CsvDelimiter controls the delimiter used when reading CSV/TXT file handler input — see File handlers → CSV and TXT.

# Migration settings

# Migrate

Type: SettingsMigrateCfg | Default: — | Required: No

Migration-specific settings (see below).

# SettingsMigrateCfg

# ForceEmailInAutoFilingFolder

Type: bool | Default: false | Required: No

When enabled, migrated emails are always stored in the auto-filing folder configured in the DMS Configuration, regardless of their original location.

# ForceEmailContentType

Type: string | Default: — | Required: No

When set, this content type is always used for migrated emails, overriding any content-type resolution that would otherwise apply.

# UseAzureBlobStorage

Type: bool | Default: false | Required: No

When enabled, files are uploaded to Azure Blob Storage during migration instead of being processed directly.

# UseAzureBlobStorageErrorAction

Type: enum (None, RecycleBin, Delete) | Default: None | Required: No

Only applies when UseAzureBlobStorage is true. Controls what happens to a migrated file when Azure Blob Storage reports warnings or errors for it: leave it in place (None), move it to the SharePoint recycle bin (RecycleBin), or delete it (Delete).

# CleanupOffice2003Documents

Type: bool (Configurator: "Cleanup Emails and Office2003 Documents") | Default: false | Required: No

When enabled, document properties and default SharePoint values are stripped from .doc/.xls/.ppt/.msg files during migration.

# CleanupOffice2007Documents

Type: bool (Configurator: "Cleanup Office2007 or newer Documents") | Default: false | Required: No

When enabled, document properties are stripped from .docx/.xlsx/.pptx files during migration.

# FileSystemCreateShortcuts

Type: bool | Default: false | Required: No

When enabled, .url shortcut files are created during filesystem migration.

# IgnoreEmailParsingError

Type: bool | Default: false | Required: No

When enabled, an email that fails to parse is still imported (without the metadata that parsing would normally extract) instead of failing the migration.

# UniqueFileNameSuffix

Type: string | Default: — | Required: No

Format string controlling how a suffix is generated to make a migrated filename unique when a naming collision occurs. {0} is replaced with the collision counter (1, 2, 3, …), using .NET composite formatting (opens new window) syntax — so a numeric format specifier such as {0:000} can be used for zero-padding.

No suffix is added for the first (non-colliding) file regardless of this setting.

Examples (counter value 1):

UniqueFileNameSuffix Result
(empty/not set) 1
{0} 1
({0}) (1)
{0:000} 001

Spacing is not added automatically — the format string is used exactly as entered. To get document (1).docx instead of document(1).docx, type a leading space before the opening parenthesis in the format value (({0}) preceded by a space).

# Email configuration

# Email

Type: EmailCfg | Default: — | Required: No

Email/SMTP settings (see below).

# EmailCfg

# Applied when (EmailCfg)

Email is only sent (for any purpose below — file-processing error alerts or matter notifications) when at least one sending method is configured:

  • UseMsGraph is true, or
  • SmtpServerHost is set, or
  • PickupDirectoryLocation is set

If none of these are configured, EmailCfg is treated as disabled and no email is ever sent by the service.

# UseMsGraph

Type: bool | Default: false | Required: No

Send email via the Microsoft Graph API (as the mailbox identified by EmailAddressFrom) instead of SMTP. Requires the app registration to have the Mail.Send application permission — see the security recommendation under Matter email notifications below.

# SmtpServerHost

Type: string | Default: — | Required: No

SMTP server hostname. Ignored when UseMsGraph is true.

# SmtpServerPort

Type: int | Default: — | Required: No

SMTP server port (typically 25, 587, or 465). If not specified, port 25 is used.

# SmtpUserName

Type: string | Default: — | Required: No

SMTP username, if the SMTP server requires authentication.

# SmtpPassword

Type: string | Default: — | Required: No

SMTP password, if the SMTP server requires authentication. Stored encrypted.

# UseDefaultCredentials

Type: bool | Default: — | Required: No

Use the service's Windows account credentials to authenticate with the SMTP server instead of SmtpUserName/SmtpPassword.

# EnableSsl

Type: bool | Default: — | Required: No

Enable SSL/TLS when connecting to the SMTP server.

# EmailAddressFrom

Type: string | Default: — | Required: No

"From" address for file-processing error alerts (see SendEmailWhenError below) and, when UseMsGraph is true, the mailbox used to send all email. Also used as the fallback "From" address for matter email notifications when EmailClientMatterCfg.EmailAddressFrom resolves to empty.

# PickupDirectoryLocation

Type: string | Default: — | Required: No

IIS SMTP pickup directory path. When set, messages are dropped as .eml files into this folder for IIS/SMTP to deliver, instead of connecting to an SMTP server directly.

# SendEmailWhenError

Type: bool | Default: true | Required: No

When a file in the monitor directory ultimately fails processing (i.e. it is not scheduled for a retry), send an error email from EmailAddressFrom to EmailAddressTo with the failure message, the source file, and the current log file attached. This is separate from the NLog-based general error alerting and from matter email notifications below — see General error alerts for the log-level alternative.

# EmailAddressTo

Type: string | Default: — | Required: No

Recipient email address for the file-processing error alerts described under SendEmailWhenError.

# Matter email notifications

Configuration path: SettingsCfg.Email.ClientMatter (Configurator: "Email ClientMatter")

When configured, an email is sent after a matter is created or updated via the Client Matter handler — for example to notify the responsible fee earner that their matter site is ready. This applies equally to both the Excel (clientmatter*.xlsx) and JSON (clientmatter*.json) inputs of that handler, since both run through the same underlying execution flow. Nothing is sent unless EmailCfg is enabled (see Applied when above) and at least a "From" address and an HTML body resolve successfully.

# NewMatter

Type: bool | Default: true | Required: No

When enabled, the notification is sent only when a new matter was created — updates to an existing matter do not trigger an email. When disabled, both new-matter and existing-matter updates send a notification.

# EmailAddressFrom / EmailAddressTo / EmailAddressCc / EmailAddressBcc

Type: string | Default: — | Required: No

Each address field is resolved through dynamic name substitution against the matter's (and client's) properties, so it can reference matter data directly, e.g. {Responsible}@firm.com. When EmailAddressFrom resolves to an empty value, the top-level EmailCfg.EmailAddressFrom is used as a fallback; if that is also empty, no email is sent.

# Subject

Type: string | Default: — | Required: No

Email subject line, resolved through dynamic name substitution against the matter's properties.

# BodyFileName

Type: string | Default: — | Required: No

Determines the HTML body, resolved through dynamic name substitution first (so it can vary per matter, e.g. {MatterType}.html):

  • If the resolved value contains <, it is used directly as literal HTML (not a filename).
  • Otherwise, it is treated as a filename. A bare filename (no path) is resolved relative to a ClientMatterEmail folder next to the service executable, and .html is appended if it has no extension.
  • If the resolved file does not exist (or BodyFileName is empty), the service falls back to ClientMatterEmail\Matter.html — or ClientMatterEmail\NewMatter.html when this is a brand-new matter. If neither fallback file exists, no email is sent.

# CultureCode

Type: string | Default: — | Required: No

Optional culture code (e.g. nl, de) used while formatting the body, affecting culture-sensitive formatting such as dates and numbers.

# HTML body template

The HTML body supports two kinds of placeholders:

  • Dynamic name fields — {PropertyName} placeholders (e.g. {MatterName}, {ClientCode}) resolved from the matter/client properties, the same mechanism used for Subject and the address fields. Properties written back after successful provisioning are also available, including {URL} (document library), {SiteURL} (matter site), and {Epona365URL}.
  • Script expressions and conditionals — the body is also evaluated as a template ( double-brace syntax) with the same properties, supporting conditional blocks such as {{#if __Error}} ... {{else}} ... {{/if}}. Two properties are always available for this: __Error (true when the provisioning operation failed) and __ErrorMessage (the failure message, only set when __Error is true).

CSS tip: many email clients strip <style> blocks — use inline style="..." attributes on each element instead. Sample templates demonstrating both approaches ship in the ClientMatterEmail folder next to the service executable.

# General error alerts

Separately from SendEmailWhenError and matter email notifications, the service's NLog configuration (Epona.ProvisioningService.exe.nlog) ships with a commented-out Mail target and logging rule that can alert on any Warn-level-or-higher log message across the whole service, not just file-processing failures. Configure the target's SMTP settings and enable the corresponding <logger> rule to activate it.

Security recommendation: when UseMsGraph is enabled, the app registration's Mail.Send permission by default allows sending mail as any mailbox in the tenant. Restrict this with an Exchange Online application access policy scoped to the specific mailbox(es) used in EmailAddressFrom, rather than leaving the permission tenant-wide.

# Yammer authentication

# Yammer

Type: YammerAuthenticationCfg | Default: — | Required: No

Yammer authentication settings.

# YammerAuthenticationCfg

# AccessToken

Type: string | Default: — | Required: No

Yammer API access token (stored encrypted).

# Archiving configuration

# Archiving

Type: ArchivingCfg | Default: — | Required: No

Archiving rules (see below).

# ArchivingCfg

# Enabled

Type: bool | Default: — | Required: No

Enable archiving functionality.

# PropertyName

Type: string | Default: — | Required: No

Property name used for archiving rules.

# PropertyValues

Type: string (list) | Default: — | Required: No

Property values that trigger archiving.

# Dynamic field value mapping

# DynamicFieldValueMapping

Type: DynamicFieldValueMapping (list) | Default: — | Required: No

Value-replacement rules applied during dynamic name resolution. Each entry maps field values from source systems (e.g., integration plugins, file handlers) to the desired SharePoint values. Supports exact matches, wildcard substring matches, and integration-specific prefixes.

See Dynamic Name for the full reference including built-in date tokens, {PropertyName} substitution, and integration prefix scoping.

  • SharepointCfg — root configuration containing global settings
  • Dynamic Name — full reference for dynamic name values and field value mappings
Last Updated: 7/7/2026, 3:18:53 PM

← Authentication →